home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d7 / lib231.arc / MAKELIST.DOC < prev    next >
Encoding:
Text File  |  1990-05-11  |  15.3 KB  |  293 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                  M a k e L i s t
  7.  
  8.                                    Version 1.0
  9.  
  10.                                Add-on Command For
  11.                                The Liberator v2.3
  12.  
  13.                     Copyright (C) 1990 Liberation Enterprises
  14.  
  15.                               All rights reserved.
  16.  
  17.                                        ~~~
  18.      DESCRIPTION:  MakeList (MAKELIST.SLC) is a compiled Telix SALT script
  19.      that will send user-defined commmands to a BBS, then capture the results
  20.      of the commands to any file.  Its purpose is to allow you to capture the
  21.      results of a Locate, New Files, or Zippy Scan command from either
  22.      PCBoard or ProDoor.  The resulting text is then automatically formatted
  23.      for use as a Liberator Download List and can be used for downloading in
  24.      the same session.  If desired, you may also manually edit the list prior
  25.      to downloading.  You define the BBS command(s) to send, and File List
  26.      name in one of the Custom Command(s) options of a Liberator v2.3 Command
  27.      File (preferably Custom Command 2).  MakeList will not work with earlier
  28.      versions of The Liberator.
  29.  
  30.      Standard conventions are used in this document to help illustrate
  31.      syntax:
  32.  
  33.       - Text inside two angle brackets <label> is used as a reference to a
  34.         certain items.  Do not type in the <label> itself, but instead
  35.         substitute it with actual text as defined below.
  36.       - Square brackets [] surround optional items.  You can leave these
  37.         items out if desired, but do not include the brackets if used.
  38.       - A vertical bar | means OR, when more than one option is available. 
  39.         The actual options to use will be on either side of the bar.  Do
  40.         not specify the actual |.
  41.       - n1, n2, etc., signifies a number (1,2,10,50, etc).
  42.       - Three periods ... means that more items of the same form may
  43.         follow.
  44.  
  45.      Now, hopefully this line below will make some sense, and not look like
  46.      secret code:
  47.  
  48.      USAGE:  @MakeList <list> <command> [/d|/e][/#n1[,n2]...][/Edit]
  49.  
  50.      Each item is explained below.  Note that <list> MUST be the first item  
  51.      specified, but following items may appear in any order.  <command> must
  52.      be separated from other options by either a space or a foward slash (/). 
  53.      If you precede <command> with a switch, make sure you leave a space
  54.      between the two.  If you follow <command> with a switch, no space is
  55.      necessary since MakeList will recognize the / as a switch.  Note that
  56.      with some program's command line switches, you may substitute the slash
  57.      (/) with a hyphen (-), but this was not implemented in MakeList.
  58.  
  59.      @MakeList = The '@' character, when used in a Liberator Custom Command,
  60.                  means to run a script.  @MakeList (or @makelist @MAKELIST)
  61.  
  62.  
  63.           The  L i b e r a t o r  v2.31               MAKELIST.DOC - Page 2
  64.  
  65.  
  66.  
  67.                  tells The Liberator to run the script MAKELIST.SLC, which
  68.                  should have accompanied this document.  The script must be
  69.                  located in the current directory, or in the directory
  70.                  defined with the Telix <Alt-O> command as your 'Script
  71.                  Directory'.  If you don't have a script directory defined in
  72.                  Telix, it is highly recommended that you do so immediately,
  73.                  then copy MAKELIST.SLC (and The Liberator) into the defined
  74.                  directory.
  75.  
  76.      <list>    = Name of file to capture results of <command> to.  The
  77.                  filename can be specified in two forms:
  78.  
  79.                  [d:][\path\]LISTNAME[.ext] -- An actual filename (drive,
  80.                  path and extension optional) or:
  81.  
  82.                  %D (or %d) -- Causes The Liberator to use the file named in
  83.                  the "Download List" option of the currently executing
  84.                  Command File.  If you specify %D without defining a filename
  85.                  in the Download List option of the same Command File, The
  86.                  Liberator will construct a filename, comprised of the name
  87.                  of the current Command File, plus the extension .DL (for
  88.                  Download List).
  89.  
  90.      <command> = PCBoard/ProDoor command(s) to send to the BBS (F)ile
  91.                  Directories, N)ew Files, L)ocate, Z)ippy Scan, etc.)  If you
  92.                  define the @MakeList command line in Custom Command 1, then
  93.                  <command> will be sent to PCBoard (unless you are already in
  94.                  ProDoor for some reason).  If you define the command in
  95.                  Custom Command 2, and a ProDoor is defined in the CFG file,
  96.                  ProDoor will be opened and the script will execute there,
  97.                  allowing you to take advantage of ProDoor commands, and
  98.                  batch transfers (this is a function of The Liberator, and
  99.                  occurs with all Custom Commands).  It is recommended that
  100.                  you use Custom Command 2 whenever possible with MakeList.
  101.  
  102.                  To specify a Ctrl (control) character within <command> (such
  103.                  as Carriage Return which is Ctrl-M), precede the character
  104.                  with a caret (^).  A vertical bar (|) in <command> causes a
  105.                  ^M (<Enter>), then waits for one of the eight Liberator
  106.                  'key' prompts defined in each Configuration.  Use either the
  107.                  | or ^M to specify more than one command if desired.  A
  108.                  tilde (~) may also be used to specify a half-second pause. 
  109.                  See the examples below for uses of these characters in
  110.                  <command>.  ^M is always sent after the final character of
  111.                  <command>, so you need not specify the final carriage
  112.                  return.  If you do specify a trailing ^M, then two carriage
  113.                  returns will be sent.
  114.  
  115.                  The "More" (PCBoard) and "ProDoor More" prompts (defined in
  116.                  each Liberator Configuration) are automatically handled by
  117.                  MakeList by sending NS (Non-Stop) when found.  The "Pause"
  118.                  prompt is also handled as usual by sending a carriage
  119.                  return.  Most times you will add an NS (non-stop) to the end
  120.  
  121.  
  122.           The  L i b e r a t o r  v2.31               MAKELIST.DOC - Page 3
  123.  
  124.  
  125.  
  126.                  of <command> to avoid the 'More' prompt, but if you forget,
  127.                  MakeList will handle these prompts for you.  If MakeList
  128.                  hangs at either of these prompts due to a different prompt
  129.                  format, you may reconfigure both directly in the board's
  130.                  Liberator CFG File, since MakeList gets the prompts directly
  131.                  from the Configuration.
  132.  
  133.      /d|/e       All text resulting from <command> is captured and inserted
  134.                  at the BEGINNING of <list> if it already exists. (This is to
  135.                  allow quick editing, and so newly listed files will be
  136.                  downloaded first.)  To change this, use the /d or /e switch
  137.                  (or /E /D if you prefer).  /d causes <list> to be Deleted if
  138.                  it is found, /e causes captured text to be appended to the
  139.                  End of <list>, if it already exists.
  140.  
  141.      /#n1[,n2] = Specifies conference(s) to execute <command> in.  This
  142.                  option, if used, must start with the '/#' characters, and NO
  143.                  SPACES are permitted until all conferences are specified. 
  144.                  You may use as many conference numbers as will fit in the
  145.                  Custom Commmand (64 character maximum), each separated by a
  146.                  comma, or omit this option entirely to execute <command>
  147.                  only in the current conference.  If more than one conference
  148.                  is specified, <command> will be sent to the BBS in each of
  149.                  the conferences.  Commas are only necessary when more than
  150.                  one number is specified, and remember not to use a space
  151.                  before or after the comma.  Note that sometimes the "Scan
  152.                  message base" question is asked after joining a conference. 
  153.                  MakeList is designed to handle this prompt, and it gets the
  154.                  prompt's format directly from the Liberator CFG file
  155.                  currently being used ('Scan Message Base' is defined on the
  156.                  PCBoard Prompts screen).
  157.  
  158.                  The correct conference numbers will be maintained in <list>
  159.                  so The Liberator will obtain files from the correct con-
  160.                  ference when <list> is used for downloading.  Note that if
  161.                  the @MakeList command is defined in Custom Command 2, AND if
  162.                  a ProDoor is defined (or if your PCBoard supports conference
  163.                  names) then you may also use the conference names as well. 
  164.                  (E.g. /#IBM,5,TELIX)
  165.  
  166.      /Edit    =  Run your Text Editor when complete to manually remove or
  167.                  rearrage text in <list>.  MakeList automatically filters out
  168.                  most extranneous text, other than file descriptions, but if
  169.                  you want to look over the list before MakeList returns
  170.                  control to The Liberator, use this switch.  You must use the
  171.                  The LibTools Configure option to define your editor before
  172.                  using this option.  Case isn't important (/EDIT or /edit
  173.                  will work fine as well), but the '/' is necessary.  Your
  174.                  editor will be called in the form <editor_name> <list>, so
  175.                  if it accepts a filename on the command line, <list> will be
  176.                  automatically loaded.  If your editor doesn't accept a
  177.                  filename on the command line, you will have to load the file
  178.                  manually, but MakeList will change to the proper directory
  179.  
  180.  
  181.           The  L i b e r a t o r  v2.31               MAKELIST.DOC - Page 4
  182.  
  183.  
  184.  
  185.                  before running the editor so you can locate the file easily.
  186.  
  187.                  Before actually running the editor, MakeList will prompt you
  188.                  to press a key, and if you are not present will sound a
  189.                  pager every ten seconds until you arrive.  If you don't
  190.                  arrive within two minutes, manual editing will be aborted
  191.                  and MakeList will return to The Liberator, where the Command
  192.                  File will continue as defined.
  193.  
  194.      EXAMPLES:
  195.  
  196.      Please note that the examples below are for use in Custom Command 1 or 2
  197.      of a Liberator v2.3 Command File, and the leading @ is necessary in each
  198.      example (specifies to run a script).  It is recommended that you use
  199.      Custom Command 2 whenever possible.
  200.  
  201.      @MakeList
  202.  
  203.       If you don't give any parameters at all, then MakeList will construct a
  204.       default <list> named <cmd_fname>.DL (<cmd_fname> is the current Command
  205.       File), and its default <command> of N S A NS (New files, Since last
  206.       time on, All areas, Non stop).  The commmand will execute in the
  207.       current conference only, and text will be inserted at the beginning of
  208.       <cmd_fname>.DL if it already exists.  Your editor will not be called
  209.       for manual editing.
  210.  
  211.      @MakeList N S A NS
  212.  
  213.       The Liberator will separate this into "N" and "S A NS" before passing
  214.       it to MakeList... the result is that MakeList opens a <list> called
  215.       "N", then sends the command S A NS (which means nothing).  In other
  216.       words, you cannot leave <list> out and just specify <command>, due to
  217.       the way The Liberator sends parameters to MakeList.
  218.  
  219.      @MakeList C:\TELIX\PCBOARD.DL
  220.  
  221.       Opens the file C:\TELIX\PCBOARD.DL, then sends the default <command> of
  222.       N S A NS to the BBS, in the current conference.  If C:\TELIX\PCBOARD.DL
  223.       already exists, then the captured lines are inserted at the BEGINNING
  224.       of the file so they will be downloaded first.  See the next example to
  225.       change this.
  226.  
  227.      @MakeList %D L *.GIF A /e /#1,10,0 /Edit
  228.  
  229.       Joins conference 1 (note the conference '/#' option used above), then
  230.       sends the command L *.GIF A to the BBS (Locate GIF files, All areas),
  231.       then conference 10 is joined (note the comma, and no space) and the L
  232.       *.GIF command is resent... then conference 0 is joined (the MAIN
  233.       conference) and the command is sent once again.  Text resulting from
  234.       all three commands is captured to the currently defined Download List
  235.       (note %D used as <list> above), and is placed at the END of the file if
  236.       it already exists (due to the /e switch... /E has the same effect). 
  237.       The defined Editor is then run to allow you to edit the list before
  238.  
  239.  
  240.           The  L i b e r a t o r  v2.31               MAKELIST.DOC - Page 5
  241.  
  242.  
  243.  
  244.       files are downloaded, to remove unwanted files, etc.  When downloading
  245.       commences, the correct conferences will be re-joined as necessary. 
  246.       Since no NS (non-stop) was given in <command>, MakeList would enter NS
  247.       (Non Stop) if a 'More' prompt did appear while the BBS was displaying
  248.       the located files.
  249.  
  250.      @MakeList TMPLIST /d /#2 Z^M~~Liberator^M1 2 U NS
  251.  
  252.       This command is a little complicated, so let's break it down:
  253.  
  254.       TMPLIST /d means capture to the file TMPLIST (note how / switches can
  255.       appear anywhere after <list>), but delete the file first, if it already
  256.       exists (due to the /d switch... /D has the same effect).  Since no
  257.       drive or path is given before TMPLIST, the file will be created in the
  258.       current directory, wherever that happens to be.  This is why it is
  259.       preferable to specify the path when possible.  Next, we have /#2 which
  260.       will cause conference 2 to be joined.  Then we have the command to
  261.       execute: 
  262.       Z^M~~Liberator^M1 2 U NS
  263.  
  264.       This is the actual <command> to send to the BBS, and it needn't be this
  265.       complicated, but ^ ~ are illustrated here.  First the "Z" would be sent
  266.       to the BBS (Zippy scan), followed by a carriage return (the <Enter>
  267.       key) because ^M signifies Ctrl-M or Carriage Return (CR).  Next, a 1
  268.       second pause will take place due to the two ~~ characters (each ~
  269.       causes a half-second pause).  This gives PCBoard a chance to come up
  270.       with the next prompt, which asks what text you want to scan for. 
  271.       "Liberator" would then be sent, along with another CR.  Then PCBoard
  272.       asks what areas to scan, and the final "1 2 U NS" are sent, which means
  273.       to scan file areas 1, 2, and the recent Uploads area.  NS is stacked on
  274.       the end to avoid the 'More' prompt.  A ^M is always appended to the end
  275.       of <command>, so you need not specify the final CR.
  276.  
  277.       Of course, this whole command can (and should) be specified without any
  278.       CR's.
  279.  
  280.      @MakeList %d Z Liberator U NS|N S A NS|L Telix A NS /#1,2
  281.  
  282.       The above would be sent as three complete commands:
  283.  
  284.         Z Liberator U NS
  285.         N S A NS
  286.         L Telix A NS
  287.  
  288.       ...since the vertical bar (|) causes a ^M (<Enter>), then waits for one
  289.       of the eight Liberator 'key' prompts before sending any more of <com-
  290.       mand>.  Since more than one conference was specified, all three
  291.       commands would be sent in each of the defined conferences.
  292.  
  293.